# Scripting

Top Previous Next

Agent Ransack supports Active Scripting to customize the search engine's file name and contents matching algorithms. When the user starts a search Agent Ransack: •Looks to see if any script is active •Creates the Active Scripting engine for each script as specified by the Prog Id entered in the 'Engine' field.

•Loads the script into the scripting engine.

Once the script is loaded Agent Ransack will then call a specific function inside the script depending on the script type:

•If the script is a 'File Name' script the function called is 'isValidFileName' and is passed the file path and name as parameters.

•If the script is a 'Containing text' script the function called is 'isValidLine' and is passed the line number and text as parameters.

Scripts are only called if the other search criteria is satisfied, i.e. file name or containing text expressions. The functions should return a boolean true or false value to indicate if the file or line is valid or not.

Examples:

Note: Please see the "Sample Scripts" sub-folder of the Agent Ransack's installation folder for some provided sample scripts.

Read-only script

The following example shows a sample file name script to limit the files returned to those that have the Read-Only attribute specified. Note: Other attributes could be used, e.g. use the '32' instead of '1' to find files with Archive attribute specified.

var objFSO = new ActiveXObject( "Scripting.FileSystemObject" );

function isValidFileName( strPath, strFileName )

{

var bIsValid = false;

try

{

var objFile = objFSO.GetFile( strPath + strFileName );

bIsValid = ( objFile.Attributes & 1 );

}

catch( e ) {}

return bIsValid;

}

Note that try...catch blocks have been used to prevent exceptions being thrown back to the search engine. If an exception occurs and is not caught by the script the search will stop.

Folders only script

Another example shows how to locate only folders.

var objFSO = new ActiveXObject( "Scripting.FileSystemObject" );

function isValidFileName( strPath, strFileName )

{

var bIsValid = false;

try

{

bIsValid = objFSO.FolderExists( strPath + strFileName );

}

catch( e ) {}

return bIsValid;

}

NOT expression script

Here's an example of how to implement NOT when contents matching using JScript's own regular expression engine (the NOT expression to be matched is entered in the 'Containing text' CustomParm field on the Scripting tab):

// An example of a NOT expression, this time using JScript's built in Regular Expression object.

var regExp = new RegExp( SearchParms.ContainingTextCustomParm );

function isValidLine( nLineNum, strText )

{

var bIsValid = true;

try

{

bIsValid = !regExp.test( strText );

}

catch( e ) {}

return bIsValid;

}

Note how the regular expression object is created outside of the function body so that it is only created and compiled once for any given search, although it may be called many times.

Excluding directories

Another variation of the NOT expression (see above) is for excluding certain directories from a search. For example, to exclude the Windows directory from a search the NOT expression on the path is simply 'C:\\Windows'. Here's an example of how to implement a NOT when path name matching (the NOT expression to be matched is entered in the 'File name' CustomParm field on the Scripting tab):

// An example of a NOT expression on a file's pathname

// using JScript's built in Regular Expression object.

var regExp = new RegExp( SearchParms.FilenameCustomParm );

function isValidFileName( strPath, strFileName )

{

var bIsValid = true;

try

{

bIsValid = !regExp.test( strPath );

}

catch( e ) {}

return bIsValid;

}

Note the use of two '\\' to represent a single '\' in 'C:\\Windows' since the backslash character is the special escape character in regular expressions.

Search Parameters Object

Scripts can access almost all the other search criteria through the object 'SearchParms'. For example, the isValidFileName script could use the Custom Parm value entered in the Scripting tab like this:

var strCustom = SearchParms.FilenameCustomParm;

SearchParms provides access to the following criteria:

CurrentFileName (String) - Currently being processed file name.

CurrentFilePath (String) - Path of currently processed file.

ContainingText (String) - Value entered in the 'Containing text' field..

ContainingTextCustomParm (String ) - Value entered in the 'Custom Parm' field for containing text script.

ContainingTextRegExp (Boolean) - Indicates if the regular expression on Containing text has been switched on.

EOLUnix (Boolean) - Indicates if EOL Unix option has been switched on.

EOLMac (Boolean) - Indicates if EOL Mac option has been switched on.

Filename (String) - Value entered in the 'File name' field.

FilenameCustomParm (String) - Value entered in the 'Custom Parm' field for file name script.

FilenameExcludeExp (Boolean) - Indicates if the 'Specifies NOT expression' has been switched on.

FilenameRegExp (Boolean) - Indicates if the regular expression on File name has been switched on.

LookIn (String) - Value entered in the 'Look in' field.

MatchFilenameCase (Boolean) - Indicates if the match case option for file name has been switched on.

MatchContentsCase (Boolean) - Indicates if the match case option for the containing text has been switched on.

ModifiedAfter (Date) - Value entered in the 'Modified After' field.

ModifiedBefore (Date) - Value entered in the 'Modified Before' field.

SearchContents (Boolean) - Indicates if the search is searching contents of files.

SearchOnePhase (Boolean) - Indicates if 'One Phase Searching' has been switched on.

SearchSubFolders (Boolean) - Indicates if the 'Search Sub Folders' has been switched on.

SizeMoreThan (Integer) - Value entered in the 'Size More Than' field.

SizeLessThan (Integer) - Value entered in the 'Size Less Than' field.

Copyright © 2026 Mythicsoft Ltd. All rights reserved.
Help file version: 9.0
PDF and CHM versions of this help file are available here:
http://mythicsoft.com/filelocatorpro/help